<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN">
<HTML>
<HEAD>
<TITLE>OpenSP - Catalogs</TITLE>
</HEAD>
<BODY>
<H1>Catalogs</H1>
<P>
The entity manager generates a system identifier for every external
entity using catalog entry files in the format defined by <A
HREF="http://www.oasis-open.org/a401.htm">SGML Open
Technical Resolution TR9401:1997</A>.  The entity manager will give an
error if it is unable to generate a system identifier for an external
entity.  Normally if the external identifier for an entity includes a
system identifier then the entity manager will use that as the
effective system identifier for the entity; this behaviour can be
changed using <CODE>OVERRIDE</CODE> or <CODE>SYSTEM</CODE> entries in
a catalog entry file.
<P>
A catalog entry file contains a sequence of entries in one of the
following forms:
<DL>
<DT>
<SAMP>PUBLIC <VAR>pubid</VAR> <VAR>sysid</VAR></SAMP>
<DD>
This specifies that <SAMP><VAR>sysid</VAR></SAMP> should be used as
the effective system identifier if the public identifier is
<SAMP><VAR>pubid</VAR></SAMP>.  <SAMP><VAR>Sysid</VAR></SAMP> is a
system identifier as defined in ISO 8879 and
<SAMP><VAR>pubid</VAR></SAMP> is a public identifier as defined in ISO
8879.
<DT>
<SAMP>ENTITY <VAR>name</VAR> <VAR>sysid</VAR></SAMP>
<DD>
This specifies that <VAR>sysid</VAR> should be used as the effective
system identifier if the entity is a general entity whose name is
<VAR>name</VAR>.
<DT>
<SAMP>ENTITY %<VAR>name</VAR> <VAR>sysid</VAR></SAMP>
<DD>
This specifies that <SAMP><VAR>sysid</VAR></SAMP> should be used as
the effective system identifier if the entity is a parameter entity
whose name is <VAR>name</VAR>.  Note that there is no space between
the <SAMP>%</SAMP> and the <SAMP><VAR>name</VAR></SAMP>.
<DT>
<SAMP>DOCTYPE  <VAR>name</VAR> <VAR>sysid</VAR></SAMP>
<DD>
This specifies that <SAMP><VAR>sysid</VAR></SAMP> should be used as
the effective system identifier if the entity is an entity declared in
a document type declaration whose document type name is <VAR>name</VAR>.
<DT>
<SAMP>LINKTYPE <VAR>name</VAR> <VAR>sysid</VAR></SAMP>
<DD>
This specifies that <SAMP><VAR>sysid</VAR></SAMP> should be used as the
effective system identifier if the entity is an entity declared in a
link type declaration whose link type name is <VAR>name</VAR>.
<DT>
<SAMP>NOTATION <VAR>name</VAR> <VAR>sysid</VAR></SAMP>
<DD>
This specifies that <SAMP><VAR>sysid</VAR></SAMP> should be used as
the effective system identifier for a notation whose name is
<SAMP><VAR>name</VAR></SAMP>.
This is relevant only with the <SAMP>-n</SAMP> option.
<DT>
<SAMP>OVERRIDE <VAR>bool</VAR></SAMP>
<DD>
<SAMP><VAR>bool</VAR></SAMP> may be <SAMP>YES</SAMP> or
<SAMP>NO</SAMP>.  This sets the overriding mode for entries up to the
next occurrence of OVERRIDE or the end of the catalog entry file.  At
the beginning of a catalog entry file the overriding mode will be NO.
A PUBLIC, ENTITY, DOCTYPE, LINKTYPE or NOTATION entry with an
overriding mode of YES will be used whether or not the external
identifier has an explicit system identifier; those with an overriding
mode of NO will be ignored if external identifier has an explicit
system identifier.
<DT>
<SAMP>SYSTEM <VAR>sysid1</VAR> <VAR>sysid2</VAR></SAMP>
<DD>
This specifies that <VAR>sysid2</VAR> should be used as the effective
system identifier if the system identifier specified in the external
identifier was <SAMP><VAR>sysid1</VAR></SAMP>.
<VAR>sysid2</VAR> should always be quoted to
ensure that it is not misinterpreted when parsed by a system that does
not support this extension.
<DT>
<A NAME="sgmldecl"><SAMP>SGMLDECL <VAR>sysid</VAR></SAMP></A>
<DD>
This specifies that if the document does not contain an SGML declaration,
the SGML declaration in <SAMP><VAR>sysid</VAR></SAMP> should be implied.
<DT>
<A NAME="dtddecl"><SAMP>DTDDECL <VAR>pubid</VAR> <VAR>sysid</VAR></SAMP></A>
<DD>
This specifies that if the document does not contain an SGML declaration
and uses a doctype declaration with public identifier 
<SAMP><VAR>pubid</VAR></SAMP>, the SGML declaration in 
<SAMP><VAR>sysid</VAR></SAMP> should be implied.
<DT>
<SAMP>DOCUMENT <VAR>sysid</VAR></SAMP>
<DD>
This specifies that the document entity is <SAMP><VAR>sysid</VAR></SAMP>.
This entry is used only with the <SAMP>-C</SAMP> option.
<DT>
<SAMP>CATALOG <VAR>sysid</VAR></SAMP>
<DD>
This specifies that <SAMP><VAR>sysid</VAR></SAMP> is the system
identifier of an additional catalog entry file to be read after this
one.  Multiple <SAMP>CATALOG</SAMP> entries are allowed and will be
read in order.
<DT>
<SAMP>BASE <VAR>sysid</VAR></SAMP>
<DD>
This specifies that relative storage object identifiers in system
identifiers in the catalog entry file following this entry should be
resolved using first storage object identifier in
<SAMP><VAR>sysid</VAR></SAMP> as the base, instead of the storage
object identifiers of the storage objects comprising the catalog entry
file.
Note that the <CODE><VAR>sysid</VAR></CODE> must exist.
<DT>
<SAMP>DELEGATE <VAR>pubid-prefix</VAR> <VAR>sysid</VAR></SAMP>
<DD>
This specifies that entities with a public identifier that has
<SAMP><VAR>pubid-prefix</VAR></SAMP> as a prefix should be resolved
using a catalog whose system identfier is
<SAMP><VAR>sysid</VAR></SAMP>.  For more details, see <A
HREF="http://www.entmp.org/fpi-urn/delegate.html">A Proposal for
Delegating SGML Open Catalogs</A>.
<DT>
<SAMP>SGML <VAR>name</VAR> <VAR>sysid</VAR></SAMP>
<DD>
This specifies that the SGML declaration body in <SAMP><VAR>sysid</VAR></SAMP>
should be used when the document starts with a reference to an SGML
declaration named <SAMP><VAR>name</VAR></SAMP>. This is an OpenSP-specific 
extension of the SGML Open catalog format. SGML declaration references 
are defined in 
<A HREF="http://www.ornl.gov/sgml/sc34/document/0029.htm">Annex K of ISO 8879</A>.
</DL>
<P>
The delimiters can be omitted from the <SAMP><VAR>sysid</VAR></SAMP>
provided it does not contain any white space.  Comments are allowed
between parameters delimited by <SAMP>--</SAMP> as in SGML.
<P>
The entity manager will look for catalog entry files as follows:
<OL>
<LI>
a file called <SAMP>catalog</SAMP> in the same directory as the
document entity, unless the environment variable
<SAMP>SP_USE_DOCUMENT_CATALOG</SAMP> has the value <SAMP>NO</SAMP> or
<SAMP>0</SAMP>;
<LI>
any catalog entry files specified using the <SAMP>-c</SAMP> option;
<LI>
a list of files specified by the environment variable
<SAMP>SGML_CATALOG_FILES</SAMP>; the list is separated by colons under
Unix and by semi-colons under MS-DOS and Windows; if this environment
variable is not set, then a system dependent list of catalog entry
files will be used.
</OL>
<P>
In fact catalog entry files are not restricted to being files: the
name of a catalog entry file is interpreted as a system identifier.
<P>
A match in one catalog entry file will take precedence over any match
in a later catalog entry file.  A more specific matching entry in one
catalog entry file will take priority over a less specific matching
entry in the same catalog entry file.  For this purpose, the order of
specificity is (most specific first):
<UL>
<LI>
<SAMP>SYSTEM</SAMP> entries;
<LI>
<SAMP>PUBLIC</SAMP> entries;
<LI>
<SAMP>DELEGATE</SAMP> entries ordered by the length of the prefix,
longest first;
<LI>
<SAMP>ENTITY</SAMP>, <SAMP>DOCTYPE</SAMP>, <SAMP>LINKTYPE</SAMP>,
<SAMP>NOTATION</SAMP> and <SAMP>SGML</SAMP> entries.
</UL>
<P>For the purpose of implying an SGML declaration, <SAMP>DTDDECL</SAMP>
entries are more specific than <SAMP>SGMLDECL</SAMP> entries.
</BODY>
</HTML>
